/**
 * AjLog - The AspectJ based logging facade
 *
 * Copyright (C) 2009 - 2010, Marko Umek. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.ajlog.core.logging;

/**
 * ILogMethod must be implemented by the facade of a specific logging framework
 * like log4j, JUL, ... .<br>
 * <br>
 * A log method is a encapsulation of a common pair of methods, the filter and
 * the execution of the logging - see here:
 * 
 * <pre>
 *    if( log.<b>isDebugEnabled</b>() ) {
 *        log.<b>debug</b>("my debug message");
 *    }
 * </pre>
 * 
 * @author Marko Umek
 * 
 */
public interface ILogMethod
    extends Cloneable {

    /**
     * Returns <code>true</code> if the (filter) log level is active. If
     * <code>false</code> {@link #log(ILogEntry)} will not be called.
     */
    public boolean isEnabled();

    /**
     * Does the actually logging by using the actually logging framework.
     * 
     * @param logEntry
     *            the log entry instance.
     */
    public void log(ILogEntry logEntry);

    /**
     * createCopy is responsible for creating a clone of the current instance. <br>
     * <br>
     * <b>Caution</b>: Returning the same instance will result in an error.
     * 
     * @param loggingInstance
     *            the logging instance the log method should be use.
     * @return a valid clone of the current instance.
     */
    public ILogMethod createCopy(Object loggingInstance);

    /**
     * isValid checks if the log method instance has been created properly and
     * can be used.
     * 
     * @return <code>true</code> if valid.
     * 
     * @see AjLogLevelMapper#createLogMethod(org.ajlog.annotations.levels.EAjLogLevel,
     *      Object)
     */
    public boolean isValid();
}
